Skip to content

refactor!: SDL3 migration#8336

Draft
AzmodiusX wants to merge 13 commits intocataclysmbn:mainfrom
AzmodiusX:SLD3-Migration
Draft

refactor!: SDL3 migration#8336
AzmodiusX wants to merge 13 commits intocataclysmbn:mainfrom
AzmodiusX:SLD3-Migration

Conversation

@AzmodiusX
Copy link
Collaborator

@AzmodiusX AzmodiusX commented Mar 18, 2026

DO NOT MERGE

This compiles for me, but I need the build system to run tests for this.

Purpose of change (The Why)

SDL3 allows for some better handling of tiles, shaders, and compute shaders.
Shaders will allow cool effects, compute shaders can be leveraged for some insane performance gains.
The latter being a must to improve lighting performance, especially high bubble sized zlight.

Describe the solution (The How)

Migrates to SDL3

Describe alternatives you've considered

The magical code in zlight will haunt me forever.
I cannot make it significantly faster, even with multi-threading (without breaking it).

Testing

Most things seem to work correctly, but who knows at this point.

What Still Needs Attention

Note: This section relied heavily on AI support due to my lacking of intimate experience or resources for the following information. I've done what I can to ameliorate this, but caution and scrutiny is advised, and help required.

1. macOS Homebrew/MacPorts package names (verify)

The Makefile has been updated to use sdl3, SDL3_image, SDL3_ttf, SDL3_mixer
as pkg-config names and sdl3-config as the config tool. Verify these match the
actual package names once SDL3 lands in Homebrew and MacPorts stable channels.
At time of writing SDL3 may only be available as sdl3 (Homebrew tap) or require
a manual install. Adjust if the package names differ.

The macOS framework path (FRAMEWORK=1) has been updated to look for SDL3.*
frameworks. SDL3 does not currently ship official .framework bundles. If macOS
framework support is required, build SDL3 from source with
-DSDL_FRAMEWORK=ON and copy the output.

4. Building docs (non-blocking)

The docs under docs/en/dev/guides/building/, docs/ko/dev/guides/building/,
and docs/ja/dev/guides/building/ still reference SDL2 package names, download
links, and build instructions. These are user-facing and should be updated to
reflect SDL3 package names and install commands before release.


Known Regression

Pitch shift is not supported. The old code manipulated raw PCM via
Mix_Chunk::abuf. MIX_Audio in SDL3_mixer is opaque; no PCM buffer is
exposed. All sounds play at their natural pitch. A future fix would use
SDL_AudioStream for sample-rate conversion.

@AzmodiusX AzmodiusX requested a review from usagirei March 18, 2026 08:09
@github-actions github-actions bot added the src changes related to source code. label Mar 18, 2026
@autofix-ci
Copy link
Contributor

autofix-ci bot commented Mar 18, 2026

Autofix has formatted code style violation in this PR.

I edit commits locally (e.g: git, github desktop) and want to keep autofix
  1. Run git pull. this will merge the automated commit into your local copy of the PR branch.
  2. Continue working.
I do not want the automated commit
  1. Format your code locally, then commit it.
  2. Run git push --force to force push your branch. This will overwrite the automated commit on remote with your local one.
  3. Continue working.

If you don't do this, your following commits will be based on the old commit, and cause MERGE CONFLICT.

@AzmodiusX AzmodiusX changed the title refactor(C++): SDL3 migration refactor: SDL3 migration Mar 18, 2026
@scarf005 scarf005 changed the title refactor: SDL3 migration refactor!: SDL3 migration Mar 18, 2026
if: ${{ env.SKIP == 'false' && matrix.tiles == 1 }}
run: |
sudo apt-get install libsdl2-dev libsdl2-ttf-dev libsdl2-image-dev libsdl2-mixer-dev libpulse-dev libflac-dev
sudo apt-get install libsdl3-dev libsdl3-ttf-dev libsdl3-image-dev libsdl3-mixer-dev
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

libsdl3-mixer-dev does not exist as an ubuntu package, the rest of the sdl3 packages are only available currently on ubuntu 25.04 or newer (and this workflow uses ubuntu 24.04)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is known, unfortunately we're gonna have to wait for a number of reasons.
I'm marking this as a draft for now. MacOS is similarly effected. We'd have to compile ourselves to skip the wait.
Hopefully won't be too long.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, if SDL3 requires a newer version of Ubuntu, I assume we'll have to change the required Ubuntu version.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stable SDL3_Mixer came out last week, so its not available on stable distro packages yet.

I don't think the runner is going to support it until 26.04 LTS (ubuntu-latest runner image is still on 24.04)
Alternatively, we'll have to CMake FetchContent / Git Submodule SDL, as to not depend on distro packaging

@AzmodiusX AzmodiusX marked this pull request as draft March 18, 2026 19:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

src changes related to source code.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants